openapi: 3.0.3
info:
  title: Check device connectivity API
  description: Service Enabling Network Function API for monitoring device connectivity
  termsOfService: http://swagger.io/terms/
  contact:
    email: project-email@sample.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.2.0
externalDocs:
  description: Product documentation at CAMARA
  url: https://github.com/camaraproject/
security:
  - { }
  - oAuth2ClientCredentials: [ ]
  - BasicAuth: [ ]
  - apiKey: [ ]
  - three_legged:
      - device-connectivity-read
servers:
  - url: https://api.orange.com/camara/device-status/orange-lab/v0
  - url: '{apiRoot}/{basePath}'
    variables:
      apiRoot:
        default: https://api.orange.com/
        description: API root
      basePath:
        default: camara/device-status/orange-lab/v0
        description: Base path for Device Connectivity API
tags:
  - name: Device Connectivity Status
    description: Operations to validate device connectivity status
paths:
  /status:
    post:
      tags:
        - Device Connectivity Status
      summary: 'Get the current connectivity status'
      operationId: getStatus
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestStatus'
        required: true
      responses:
        '200':
          description: Contains information about current connectivity status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectivityEventReport'
        '400':
          $ref: "#/components/responses/Generic400"
        '401':
          $ref: "#/components/responses/Generic401"
        '403':
          $ref: "#/components/responses/Generic403"
        '404':
          $ref: "#/components/responses/Generic404"
        '500':
          $ref: "#/components/responses/Generic500"
        '503':
          $ref: "#/components/responses/Generic503"
components:
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '{tokenUrl}'
          scopes: { }
    BasicAuth:
      type: http
      scheme: basic
    apiKey:
      type: apiKey
      description: API key to authorize requests
      name: apikey
      in: query
    three_legged:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            device-connectivity-read: Read device roaming status
  schemas:
    ConnectivityEventReport:
      type: "object"
      properties:
        ueId:
          $ref: "#/components/schemas/UeId"
        uePort:
          $ref: '#/components/schemas/Port'
        eventType:
          $ref: "#/components/schemas/ConnectivityEventType"
        eventStatus:
          $ref: "#/components/schemas/EventStatusType"
      required:
        - ueId
        - eventType
        - eventStatus
    UeId:
      description: User equipment identifier
      type: object
      properties:
        externalId:
          $ref: '#/components/schemas/ExternalId'
        msisdn:
          $ref: '#/components/schemas/MSISDN'
        ipv4Addr:
          $ref: '#/components/schemas/Ipv4Addr'
        ipv6Addr:
          $ref: '#/components/schemas/Ipv6Addr'
      minProperties: 1
    ExternalId:
      type: string
      example: '123456789@domain.com'
    MSISDN:
      type: string
      pattern: '^\+?[0-9]{5,15}$'
      example: '123456789'
      description: Subscriber number in E.164 format (starting with country code). Optionally prefixed with '+'.
    Ipv4Addr:
      type: string
      format: ipv4
      pattern: '^([01]?\d\d?|2[0-4]\d|25[0-5])(?:\.(?:[01]?\d\d?|2[0-4]\d|25[0-5])){3}(\/([0-9]|[1-2][0-9]|3[0-2]))?$'
      example: '192.168.0.1/24'
      description: |
        IPv4 address may be specified in form <address/mask> as:
          - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule.
          - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24.
            In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version.
    Ipv6Addr:
      type: string
      format: ipv6
      allOf:
        - pattern: '^((:|(0?|([1-9a-f][0-9a-f]{0,3}))):)((0?|([1-9a-f][0-9a-f]{0,3})):){0,6}(:|(0?|([1-9a-f][0-9a-f]{0,3})))(\/(([0-9])|([0-9]{2})|(1[0-1][0-9])|(12[0-8])))?$'
        - pattern: '^((([^:]+:){7}([^:]+))|((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?))(\/.+)?$'
      example: '2001:db8:85a3:8d3:1319:8a2e:370:7344'
      description: |
        IPv6 address, following IETF 5952 format, may be specified in form <address/mask> as:
          - address - The /128 subnet is optional for single addresses:
            - 2001:db8:85a3:8d3:1319:8a2e:370:7344
            - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128
          - address/mask - an IP v6 number with a mask:
            - 2001:db8:85a3:8d3::0/64
            - 2001:db8:85a3:8d3::/64
    ConnectivityEventType:
      type: string
      enum:
        - UE_ROAMING_STATUS
    EventStatusType:
      type: string
      enum:
        - ROAMING_ON
        - ROAMING_OFF
    RequestStatus:
      type: object
      properties:
        ueId:
          $ref: '#/components/schemas/UeId'
        uePort:
          $ref: '#/components/schemas/Port'
        eventType:
          $ref: '#/components/schemas/ConnectivityEventType'
      required:
        - ueId
        - eventType
    Port:
      description: User equipment port. Device port may be required along with IP address to identify the target device
      type: integer
      minimum: 0
      maximum: 65535
      example: 5060
    ErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description
  responses:
    Generic400:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: INVALID_ARGUMENT
            status: 400
            message: "Invalid input"
    Generic401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: UNAUTHENTICATED
            status: 401
            message: "Authorization failed: ..."
    Generic403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: PERMISSION_DENIED
            status: 403
            message: "Operation not allowed: ..."
    Generic404:
      description: Not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: NOT_FOUND
            status: 404
            message: "The specified resource is not found"
    Generic500:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: INTERNAL
            status: 500
            message: "Internal server error"
    Generic503:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: UNAVAILABLE
            status: 503
            message: "Service unavailable"
